/**
 *	TrueMusic - simple Java music player
 *
 *	TrueMusic is free software; you can redistribute it
 *	and/or modify it under the terms of the GNU General
 *	Public License as published by the Free Software
 *	Foundation; either version 2 of the License or (at
 *	your option) any later version.
 *
 *	This program is distributed in the hope that it will be
 *	useful but WITHOUT ANY WARRANTY; without even the
 *	implied warranty of the MERCHANTABILITY or FITNESS FOR
 *	A PARTICULAR PURPOSE. See the GNU General Public
 *	License for more details.
 *
 *	Copyright (c)2005-2007 Ryan Macnak <rmacnak@gmail.com>
 */

package com.servequake.truemusic;

/**
 * Abstraction for audio playback. (NOTE: Implemations cannot extend thread because of the stop() method)
 */
public interface Audio
{
	/**
	 * Return the file extensions supported by this format, lowercase and include the dot (ex: ".mp3")
	 */
	public String[] getExtensions();

	/**
	 * Called to load an audio resource (file/stream); an Audio format is expected to have a no-arg constructor.
	 * @throw Exception if this format cannot play the audio at the given resource
	 */
	public void load(String resource, PlaybackListener l) throws Exception;

	/**
	 * Called to start playback; if already playing, restart to beginning.
	 */
	public void play();

	/**
	 * Called to pause or unpause playback (resources may be left open).
	 */
	public void pause();

	/**
	 * Called to stop playback (set to beginning and pause); all resources should be released (streams, decorders, threads, ...).
	 */
	public void stop();

	/**
	 * Return wether the audio is currently being played.
	 */
	public boolean isPlaying();

	/**
	 * Return the title of this audio or an empty string if unknown.
	 */
	public String getTitle();

	/**
	 * Return the artist of this audio or an empty string if unknown.
	 */
	public String getArtist();

	/**
	 * Return the album of this audio or an empty string if unknown.
	 */
	public String getAlbum();

	/**
	 * Return the track number of this audio or an empty string if unknown.
	 */
	public String getTrack();

	/**
	 * Return the lyrics of this audio or an empty string if unknown.
	 */
	public String getLyrics();

	/**
	 * Return the genre of this audio or an empty string if unknown.
	 */
	public String getGenre();

	/**
	 * Return the title and artist in the form "Title" by Artist, or the resource name if the title and artist are not known.
	 */
	public String toString();

	/**
	 * Return the number of frames in this audio resource, return 0 if unknown (perhaps like in a live stream).
	 */
	public int getFrames();

	/**
	 * Seek to the given frame, ignore if seeking not supported. 
	 */
	public void seek(int frame);

	/**
	 * Return the resource name given at load()
	 */
	public String getResource();

	/**
	 * Return human readable name of format (ex: "128kbps mp3" or "WAV").
	 */
	public String formatName();
}
